# Snow CLI User Guide - Sub-Agent Configuration

Welcome to Snow CLI! Agentic coding in your terminal.

## What's New (#194)

| Capability              | Description                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Project Markdown agents | Scan `.snow/agents/**/*.md` (and optional `~/.snow/agents/**/*.md`); schedulable without editing `sub-agents.json`             |
| Merge priority          | `project .snow/agents` > `global ~/.snow/agents` > `~/.snow/sub-agents.json` > builtin                                         |
| `ROLE-*.md`             | Does **not** register a new `agentId` (role overlay only)                                                                      |
| Unknown-tool warn       | Unregistered frontmatter `tools` names are **warned**; declaration is not silently dropped; runtime still filters by allowlist |
| `beforeSubAgentStart`   | Hook can inject/rewrite the prompt before spawn (see [Hooks Configuration](./07.Hooks%20Configuration.md))                     |

## What are Sub-Agents

Sub-agents are branches of the main workflow in Snow CLI, designed to handle specific individual tasks to save context usage in the main workflow.

## Three Built-in System Sub-Agents

- Explore Agent - An exploration agent for searching code functionality for the main workflow, focusing on locating code positions.

- Plan Agent - A planning agent for developing comprehensive coding plans and guidance for the main workflow.

- General Purpose Agent - A general-purpose agent that provides common coding functionality for the main workflow, suitable for completing tasks that are singular but involve many files (e.g., internationalization).

## Sub-Agent Workflow

```mermaid
graph TB
Start([User Initiates Task]) --> MainProcess[Main Workflow Main Agent]

MainProcess --> Check{Does it need<br/>a sub-agent?}

Check -->|No| DirectHandle[Main workflow handles directly]
DirectHandle --> End([Return Result])

Check -->|Yes| SelectAgent{Select sub-agent type}

SelectAgent -->|Code exploration| ExploreAgent[Explore Agent<br/>Exploration Agent]
SelectAgent -->|Make plan| PlanAgent[Plan Agent<br/>Planning Agent]
SelectAgent -->|General coding| GeneralAgent[General Purpose Agent<br/>General-Purpose Agent]

ExploreAgent --> SendTask[Main workflow sends task prompt]
PlanAgent --> SendTask
GeneralAgent --> SendTask

SendTask --> SubProcess[Sub-agent receives task]

SubProcess --> Isolate[Independent context environment<br/>Isolated from main workflow]

Isolate --> SpecializedWork{Specialized direction processing}

SpecializedWork -->|Explore agent| SearchCode[Search code positions<br/>Analyze code structure]
SpecializedWork -->|Plan agent| MakePlan[Develop coding plan<br/>Provide guidance]
SpecializedWork -->|General agent| GeneralWork[Execute general coding<br/>Process batch files]

SearchCode --> Complete[Processing complete]
MakePlan --> Complete
GeneralWork --> Complete

Complete --> Return[Send results back to main workflow]

Return --> MainReceive[Main workflow receives results]

MainReceive --> End

style MainProcess fill:#e1f5ff
style ExploreAgent fill:#fff4e1
style PlanAgent fill:#ffe1f5
style GeneralAgent fill:#e1ffe1
style Isolate fill:#ffe1e1
style SubProcess fill:#f0f0f0
style Return fill:#e1ffe1
```

### Workflow Description

1. **Main Workflow Assessment**: After receiving a user task, the main workflow first evaluates whether a sub-agent is needed.
2. **Sub-Agent Selection**: Select an appropriate sub-agent based on the task type:

   - **Explore Agent**: Deep code exploration (5+ files), complex dependency tracing
   - **Plan Agent**: Breaking down complex features, major refactoring planning
   - **General Purpose Agent**: Batch modifications (5+ files), systematic refactoring

3. **Task Dispatch**: The main workflow sends a task prompt containing complete context to the sub-agent.

4. **Independent Processing**: The sub-agent processes the task in an independent context environment, completely isolated from the main workflow.

5. **Specialized Processing**: Each sub-agent performs targeted processing according to its specialized direction.

6. **Return Results**: After processing is complete, the sub-agent sends the results back to the main workflow.

7. **Main Workflow Continues**: The main workflow receives the results and continues with subsequent work.

### Key Features

- **Context Isolation**: Sub-agents have independent context that does not affect the main workflow's conversation history.
- **One-Way Communication**: Main workflow → Send task → Sub-agent → Return results → Main workflow
- **Specialized Division of Labor**: Each sub-agent focuses on a specific domain, improving processing efficiency.
- **Resource Conservation**: Prevents the main workflow context from being occupied by extensive exploration or planning information.

## Project Markdown Sub-Agents

In addition to the configuration UI and `~/.snow/sub-agents.json`, you can define sub-agents as Markdown files committed with the repo. They become discoverable and schedulable without editing `sub-agents.json`.

### Scan paths

- Project: `.snow/agents/**/*.md`
- Global (optional): `~/.snow/agents/**/*.md`

### Merge priority (higher wins)

```
project .snow/agents > global ~/.snow/agents > ~/.snow/sub-agents.json > builtin
```

### Markdown format

```markdown
---
id: trellis-implement
name: trellis-implement
description: Implement features from Trellis task
tools:
  - filesystem-read
  - filesystem-edit
  - terminal-execute
  - ace-search
---

You implement the active Trellis task using project specs.
```

Fields:

- `id`: optional; defaults to filename stem
- `name`: optional; defaults to `id`
- `description`: description
- `tools`: tool list (array or single string)
- `role`: optional frontmatter; body is used as role when omitted

Notes:

- Invalid markdown is skipped with a warning (no crash)
- `ROLE-*.md` under project root / `~/.snow` does **not** register a new `agentId` (role overlay only)
- Once discovered, agents are schedulable via `#agentId` / the picker
- Unknown tools in frontmatter are **warned** (declaration is not silently dropped; runtime still filters by allowlist)

## Sub-Agent Configuration Management

### Adding a Sub-Agent

You can create custom sub-agents through the configuration interface to meet specific business needs.

#### Operation Steps

1. **Enter Configuration Interface**

   - Select "Sub-Agent Configuration" in the main menu
   - Select "Add Sub-Agent"

2. **Basic Information Configuration**

   Fill in the following fields as prompted by the interface:

   - **Agent Name** (Required)

     - Enter the name of the sub-agent
     - Suggest using descriptive names like "Code Review Agent", "Testing Agent", etc.
     - Press Enter to confirm and move to the next field

   - **Description** (Required)

     - Enter the function description of the sub-agent
     - Describe in detail the purpose and application scenarios of this sub-agent
     - **Role Definition** (Required)
     - Define the role and behavioral norms of the sub-agent
     - This is the sub-agent's own role instructions. At runtime it is appended to the prompt sent to the sub-agent.
     - Example:
       ```
       You are a professional code review assistant.
       Your responsibilities are:
       1. Check code quality and compliance
       2. Discover potential bugs and security issues
       3. Provide improvement suggestions and best practices
       ```
     - Press Enter to confirm and move to the next field

3. **Advanced Configuration Options**

   **Important Reminder**: Sub-agents no longer select **System Prompt** or **Custom Request Headers** separately. Both are taken from the selected **Configuration Profile** (Profile), because the profile already contains these settings.

   - **Configuration Profile** (Optional)

     - Specify a dedicated API configuration profile for the sub-agent
     - Purpose: Allow the sub-agent to use different API endpoints, different models, and the system prompt + request headers defined in that profile
     - Operation:
       - Use ↑/↓ arrow keys to browse available profiles
       - Press Space to select/deselect
       - Use ←/→ arrow keys to quickly switch between configuration options
       - Marker description: `❯` indicates cursor position, `[✓]` indicates selected
     - Application scenarios:

       - Let the sub-agent use more powerful models
       - Let the sub-agent use different API providers
       - Allocate different billing accounts for different sub-agents
       - Bind different system prompts/request headers via different profiles

       - Set different request priorities

4. **Tool Permission Configuration**

   Select the tools that the sub-agent can use:

   - Use ↑/↓ arrow keys to navigate between tool categories
   - Use ←/→ arrow keys to switch between tool categories
   - Press Space to select/deselect tools
   - Tool categories include:
     - Filesystem tools (filesystem-read, filesystem-create, filesystem-edit, etc.)
     - ACE code search tool (`ace-search` with action: find_definition / find_references / semantic_search / file_outline / text_search)
     - Codebase tools (codebase-search)
     - Terminal tools (terminal-execute)
     - TODO management tools
     - Web search tools
     - MCP tools (if configured)

   **Suggestion**: Only grant the minimum set of permissions needed for the sub-agent to complete its tasks.

5. **Save Configuration**

   - Press Ctrl+S to save the configuration
   - The system will automatically validate the configuration's completeness
   - Return to the main menu after successful save

#### Configuration Inheritance Explanation

When creating a new sub-agent, if no **Configuration Profile** (Profile) is specified, the sub-agent will follow the currently active profile of the main workflow. This means:

- The sub-agent will use the same API configuration and model as the main workflow
- The sub-agent will use the system prompt and request headers defined in that profile (and then apply its own role definition on top)

### Editing a Sub-Agent

You can edit existing sub-agent configurations, including the three built-in system agents.

#### Operation Steps

1. **Enter Edit Interface**

   - Select "Sub-Agent Configuration" in the main menu
   - Select the sub-agent to edit

2. **Edit Restrictions Explanation**

   **System Built-in Agents** (Explore Agent, Plan Agent, General Purpose Agent):

   - Name, description, and role definition are read-only and cannot be modified
   - The interface will display "(System Built-in - Not Modifiable)" prompt
   - Can modify: Tool permissions, configuration profile

   **Custom Agents**:

   - All fields can be modified

3. **Modify Configuration**

   Navigation and operation methods are the same as adding an agent:

   - Use ↑/↓ arrow keys to navigate between fields
   - Use ←/→ arrow keys to switch between configuration options
   - Press Space to select/deselect
   - Directly input modification content in text fields

4. **Save Changes**

   - Press Ctrl+S to save changes
   - The system will validate the modified configuration
   - Return to the main menu after successful save

#### Edit Configuration Inheritance Explanation

When editing an existing sub-agent:

- If the sub-agent already has custom configurations, the interface will display and load these configurations
- If the sub-agent does not have custom configurations:
  - When editing a copy of a system built-in agent, it will automatically inherit the current main workflow's configuration as default values
  - When editing an existing custom agent, configurations will not be automatically filled (remain unselected)

### Configuration Best Practices

1. **Clear Role Definition**

   - Clearly describe the scope of responsibilities of the sub-agent
   - Provide specific work steps or checklists
   - Specify output format and quality standards

2. **Reasonable Tool Permission Allocation**

   - Follow the principle of least privilege
   - Read-only tasks do not grant write tools
   - Exploration tasks do not grant execution tools

3. **Good Use of Configuration Isolation**

   - Configure different sub-agents for different types of tasks
   - Use different configuration profiles (Profile) to control cost and model selection
   - Use different configuration profiles (Profile) to bind different system prompts and request headers

4. **Test Configuration Effects**
   - Perform small-scale testing after creation
   - Observe whether the sub-agent's behavior meets expectations
   - Adjust role definition and tool permissions based on actual effects

### Keyboard Shortcuts

- **↑/↓**: Navigate between options or scroll lists
- **←/→**: Switch between fields (configuration options, tool categories)
- **Space**: Select/deselect (tools, configuration options)
- **Enter**: Confirm input and move to next field
- **Ctrl+S**: Save configuration
- **Ctrl+C** or **ESC**: Cancel and return

## Quick Sub-Agent Selection

In addition to using the `/agent-` command to open the sub-agent selection panel, you can also use the `#` symbol in the input box to quickly trigger the sub-agent picker:

### How to Use

1. **Trigger the picker**: Type `#` in the input box to automatically pop up the sub-agent selection panel
2. **Search and filter**: Type `#keyword` to filter sub-agents by ID, name, or description
3. **Select sub-agent**: Use arrow keys to select a sub-agent, press Enter to confirm. The system will automatically insert `#subAgentID ` into the input box

### Examples

```
#explore     → Select explore sub-agent
#plan        → Select plan sub-agent
#general     → Select general sub-agent
```

### Notes

- The `#` symbol must not be preceded by `@` (e.g., `@#` or `@@#` will not trigger the sub-agent picker, but the file picker)
- If you type a space or newline after `#`, the picker will automatically close
- Press ESC to close the sub-agent selection panel

## Sending Messages to Running Sub-Agents

When a sub-agent is running, you can use the `>>` command to send messages to specific running sub-agents, enabling real-time interaction with the main workflow.

### How to Use

1. **Trigger the picker**: Type `>>` at the beginning of the input box (leading whitespace is allowed) to pop up the list of currently running sub-agents
2. **Select sub-agents**:
   - Use `↑/↓` arrow keys to navigate
   - Use `Space` to select/deselect sub-agents (supports multi-select)
   - If no sub-agent is explicitly selected, the currently highlighted item will be auto-selected when you press Enter
3. **Send message**: Press `Enter` to confirm selection, then type your message and send

### Visual Tag Explanation

After selecting sub-agents, a visual tag will appear in the input box:

```
[»Explore Agent#abcd: Investigating project architecture...] Please continue analyzing
```

- `»` symbol (U+00BB): Used to avoid re-triggering the picker
- `Explore Agent`: Sub-agent name
- `#abcd`: Last 4 characters of instance ID (ensures uniqueness)
- `Investigating project architecture...`: Short summary of the task prompt

### Message Routing Mechanism

The actual sent message contains a special marker:

```
# SubAgentTarget:instanceId:agentName
Your message content
```

The system routes the message to the corresponding sub-agent based on these markers.

### Use Cases

- **Follow-up details**: Ask about a specific function implementation while the sub-agent is exploring code
- **Correct direction**: Send correction information when you notice the sub-agent misunderstood
- **Add context**: Inform the working sub-agent of important information you just remembered
- **Batch instructions**: Send the same instruction to multiple running sub-agents simultaneously

### Notes

- `>>` must appear at the **beginning** of the input box (leading whitespace is ignored) to trigger
- If a sub-agent has completed or exited, it will not appear in the selection list
- Press `ESC` to close the selection panel
- The selection panel will auto-close when you delete `>>`

### Common Questions

**Q: Can sub-agents use the context of the main workflow?**

A: No. Sub-agents are completely isolated from the main workflow's context. The main workflow needs to provide all necessary context information in the prompt when calling a sub-agent.

**Q: How can I make a sub-agent use a more powerful model?**
A: In the configuration profile (Profile) option, select a profile that uses a more powerful model for the sub-agent.

**Q: What is the difference between the system prompt in a profile and a sub-agent's role definition?**

A: The role definition is the sub-agent's own behavioral specification (entered/edited in the sub-agent config). The system prompt in a configuration profile (Profile) is a profile-level constraint that affects both the main workflow and any sub-agent that uses that profile. At runtime, the sub-agent uses the profile's system prompt as the base, then applies the sub-agent's role definition on top.

**Q: Will editing a system built-in agent affect the original configuration?**
A: No. The core definitions (name, description, role) of system built-in agents are read-only. You can only modify their tool permissions and configuration profile (Profile), and these modifications only affect your usage without changing the system presets.

**Q: How do I delete a custom sub-agent?**

A: Select the sub-agent to delete in the sub-agent list, press the Delete key or select the delete option. System built-in agents cannot be deleted.